Query IBAN Holder Name

Overview

This API verifies whether a provided account holder's name matches the corresponding IBAN. It is typically used to validate recipient information during fund transfers.

API URL

• UAT (Testing): https://uat.test2pay.com/sgs/api/transfer/getIbanHolderName
• Production: https://api.payby.com/sgs/api/transfer/getIbanHolderName

Request Parameters

HTTP Headers

Attributes

• Content-Language String

  • Language in which the response message will be used.
  • Currently, only English is supported.
  • Example value: en
  • Maximum length: 10

• Content-Type String Required

  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/<format> (e.g., application/json)
  • Example value: application/json

• sign String Required

  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.

• Partner-Id String Required

  • Merchant ID of your account.
  • Example value: 200001200101
  • Maximum length: 12

HTTP Body

• requestTime Timestamp Required

  Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.

  Example value: 1581493898000

• bizContent Object

  Attributes

  • merchantOrderNo String Required

    • Unique identifier for the merchant's order.
    • Example value: Me23484

  • holderName String Required

    • Name of the beneficiary. Transmitted securely (encrypted).
    • Example value: Bruce Lee

  • iban String

    • International Bank Account Number. Transmitted securely (encrypted).
    • Example value: -

  • swiftCode String

    • Improves accuracy if provided.
    • Example value: ARABAEADDER

  • beneficiaryAddress String

    • Transmitted securely.
      If the bank account is personal, this field is required.
      The combined length of holderName and beneficiaryAddress must not exceed 140 characters, or the transfer may fail.
    • Example value: Liwa Street off Khaliffa Street

  • amount Money Required

    • Payment amount for the transaction.
    • Example value: 12.34

  • memo String Required

    • Remarks or notes for the payment.
    • Example value: Bonus

  • notifyUrl String

    • URL for receiving backend notifications.
    • Example value: -

  • accountNo String

    • Transmitted securely (available since v2.1).
    • Example value: 2000000000001

  • networkCode String

    • Defaults to LOCAL (available since v2.1).
    • Example value: LOCAL

  • bankName String

    • Name of the bank.
    • Example value: (empty)

  • countryCode String

    • Defaults to AE (available since v2.1).
    • Example value: AE

  • cityCode String

    • Available since v2.3.
    • Example value: (empty)

  • fundoutCurrencyCode String

    • Defaults to AED (available since v2.1).
    • Example value: AED

  • fedwireCode String

    • Fedwire code (available since v2.1).
    • Example value: -

  • branchName String

    • Name of the bank branch.
    • Example value: -

  • intermediaryBank String

    • Intermediary bank code (available since v2.1).
    • Example value: -

  • beneficiaryType String

    • Defaults to IBAN (available since v2.1).
    • Example value: IBAN

  • purposeCode String

    • Code indicating the purpose of the transaction.
    • Example value: COM

GetIbanHolderNameRequest

• holderName String(256) Required

  • Encrypted account holder name.

• iban String(256) Required

  • Encrypted IBAN number.

Request Sample

Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "<signature_string>"
}

Http Body
{
    "body": {
        "bizContent": {
            "holderName": "<encrypted_holder_name>",
            "iban": "<encrypted_iban>"
        },
        "requestTime": 1585142880000
    }
}

Response Parameters

HTTP Headers

Attributes

• Content-Language String

  • Language in which the response message will be used.
  • Currently, only English is supported.
  • Example value: en
  • Maximum length: 10

• Content-Type String Required

  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/<format> (e.g., application/json)
  • Example value: application/json

• sign String Required

  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.

• Partner-Id String Required

  • Merchant ID of your account.
  • Example value: 200001200101
  • Maximum length: 12

HTTP Body

• head ResponseHeader Required

  • Response metadata.

• body GetIbanHolderNameResponse

  • Core response payload.

  • ibanHolderName IbanHolderName Required

    • Contains the name match result.

Response Sample

Http Header
{
    "sign": "<response_signature>"
}

Http Body
{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "1133"
    },
    "body": {
        "ibanHolderName": {
            "holderNameMask": "xxx*** xxx*** xxx***",
            "nameMatchingLevel": "1",
            "nameMatchingResult": "TRUE"
        }
    }
}

Return Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success	-
400	INVALID_PARAMETER	Invalid parameter	Adjust request parameters.
400	REQUESTTIME_TOO_EARLY	Request time is too early	Adjust request time.
400	REQUESTTIME_TOO_LATER	Request time is too late	Adjust request time.
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency.
403	UNAUTHORIZED	Unauthorized API call	Contact PayBy.
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy.
500	SYSTEM_ERROR	System error	Contact PayBy and retry.
504	SERVICE_TIMEOUT	Service timeout	Retry later.
601	RISK_FAIL	Risk control validation failed	Adjust business logic.
62101	WRONG_IBAN_FORMAT	Incorrect IBAN format	Correct IBAN format.
62102	NAME_NOT_FOUND	Name not found for IBAN	Use a valid IBAN.
62103	QUERY_API_UNAVAILABLE	Query interface unavailable	Retry later.